<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * implementation for uploading files with php 
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category    File Handling
 * @package     Upload
 * @author      Kazuyoshi Tlacaelel <kazu.php@gmail.com> 
 * @copyright   2007 Kazuyoshi Tlacaelel
 * @license     http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version     SVN : $Id
 */

/**
 * iUpload 
 * 
 * @category    File Handling
 * @package     Upload
 * @copyright   2007 Kazuyoshi Tlacaelel
 * @author      Kazuyoshi Tlacaelel <ktlacaelel@gmail.com> 
 * @license     PHP Version 3.0 {@link http://www.php.net/license/3_0.txt}
 */

/**
 * File Upload Handler
 *
 * A simple interface to facilitate the handling of file uploads
 *
 * <code> 
 * // sample form
 * <input type=file name=myfile>
 *
 * // define the upload you wish to handle 
 * $upload = new Upload('myfile');
 *
 * // find out if the file is being received at all
 * if ($upload->wasRecived()) {
 *
 *     // define the files destination on the server
 *     $upload->setDestination('my/folder/');
 *
 *     // decide weather or not it should be overrided
 *     // if false a hash will be created
 *     $upload->override(true);
 *     
 *     if ($upload->mergeble()) {
 *         $upload->rename(uniqid() . '.txt');
 *     }
 *
 *     // save upload to destination
 *     $upload->save();
 * } else {
 *     echo ' file was not recived !';
 * }
 *
 * </code> 
 * 
 * @category    File Handling
 * @package     Upload
 * @copyright   2007 Kazuyoshi Tlacaelel
 * @author      Kazuyoshi Tlacaelel <ktlacaelel@gmail.com> 
 * @license     PHP Version 3.0 {@link http://www.php.net/license/3_0.txt}
 */
class Upload
{
    protected

    /**
     * upload form parameter
     *
     * html-input-tag's name attribute
     *
     * <code> 
     *
     * <input type=file name=$param>
     *
     * </code> 
     * 
     * @var     string
     * @access  protected
     */
    $param,

    /**
     * destination 
     * 
     * @var     string
     * @access  protected
     */
    $destination,

    /**
     * filename 
     * 
     * @var     string
     * @access  protected
     */
    $filename;

    /**
     * uploads file-extension 
     * 
     * @var     string
     * @access  public
     */
    public $extension = NULL;

    /**
     * __construct 
     * 
     * @param   string  $param 
     * <code>
     *
     * // the name of your file html tag, in the example below it 
     * would be "myfile" 
     * <input type=file name=myfile>
     *
     * </code>
     *
     * @access  public
     * @return  void
     */
    public function __construct($param)
    {
        $this->param = $param;
        $this->destination = dirname(__FILE__) . DIRECTORY_SEPARATOR;
        $this->filename = $_FILES[$this->param]['name'];
        $this->extension = $this->getExtension();
    }

    /**
     * finds out if the file was received
     * 
     * @access  public
     * @return  boolean
     */
    public function wasRecived()
    {
        return isset($_FILES[$this->param]);
    }

    /**
     * upload destination definer 
     *
     * declares the destination of the uploaded file, returnin true or 
     * false if the given path is valid
     * 
     * @param   string      $path 
     * @access  public
     * @return  boolean
     */
    public function setDestination($path)
    {
        $this->destination = $path;
        return is_dir($path);
    }

    /**
     * upload overriding option
     *
     * tells the object to do override or create a hash for filename 
     * so no files are overrided 
     * 
     * @param   boolean     $descision 
     * @access  public
     * @return  void
     * @see     rename(), mergeble()
     */
    public function override($descision)
    {
        if (!$descision) $this->filename = $this->createNewFilename();
    }

    /**
     * unique filename generator
     * 
     * generates a unique filename sufixed by $sufix if none is given 
     * 'upload_' is used instead
     *
     * @param   string      $sufix 
     * @access  public
     * @return  string 
     */
    public function createNewFilename($sufix = 'upload_')
    {
        return hash::generate($sufix) . '.' . $this->extension;
    }

    /**
     * upload renamer
     *
     * alters the filename of the upload
     *
     * @param   mixed       $filename 
     * @access  public
     * @return  void
     */
    public function rename($filename)
    {
        $this->filename = $filename;
    }

    /**
     * retrives the extension of the file that is being uploaded
     * 
     * @access  public
     * @return  string
     */
    public function getExtension()
    {
        $arr = preg_split('/[.]/', $_FILES[$this->param]['name']);
        return $arr[count($arr) -1];
    }

    /**
     * upload existance checker
     * 
     * finds out if a file with the same name as the upload already 
     * exists in the destination path
     *
     * @access  public
     * @return  void
     * @see     setDestination()
     */
    public function mergeble()
    {
        return file_exists($this->destination . $this->filename);
    }

    /**
     * upload saver
     *
     * saves the upload to the provided destination
     * 
     * @access  public
     * @return  boolean
     * @see     setDestination(), rename(), override(), mergeble()
     */
    public function save()
    {
        return move_uploaded_file(
                $_FILES[$this->param]['tmp_name'],
                $this->destination . $this->filename
                );
    }
}

?>
